
package org.apache.ibatis.session;

import org.apache.ibatis.cursor.Cursor;
import org.apache.ibatis.executor.BatchResult;

import java.io.Closeable;
import java.sql.Connection;
import java.util.List;
import java.util.Map;

/**
 * fxbmybatis
 *
 *The primary Java interface for working with MyBatis.
 *      java程序使用mybatis的主要接口。
 *Through this interface you can execute commands, get mappers and manage transactions.
 *  通过这个接口执行命令，获取映射器，管理事务
 *
 *
 *  Closeable是一个数据的来源或者目的地是可以被关闭掉的。
 *  调用close方法，来释放对象所在的资源。比如打开文件。
 *
 * @author Clinton Begin
 * @date 2018-06-07
 */
public interface SqlSession extends Closeable {

    /**
     * 根据声明的key检索出一行
     * 也就是说根据你传入的sql语句查出来对应的元组(关系型数据库)。
     * 比如： select * from t_table_name where id='1'
     * Retrieve a single row mapped from the statement key
     * @param <T> the returned object type
     * @param statement
     * @return Mapped object
     */
    <T> T selectOne(String statement);

    /**
     *  也就是说根据你传入的sql语句查出来对应的元组(关系型数据库)。
     *  比如：select * from t_table_name where id=?,1
     * Retrieve a single row mapped from the statement key and parameter.
     * @param <T> the returned object type
     * @param statement Unique identifier matching the statement to use.
     * @param parameter A parameter object to pass to the statement.
     * @return Mapped object
     */
    <T> T selectOne(String statement, Object parameter);

    /**
     * Retrieve a list of mapped objects from the statement key and parameter.
     *  根据sql检索出符合条件的元组列表
     *
     * @param <E> the returned list element type
     * @param statement Unique identifier matching the statement to use.
     * @return List of mapped object
     */
    <E> List<E> selectList(String statement);

    /**
     * Retrieve a list of mapped objects from the statement key and parameter.
     * 根据sql检索出符合条件的元组列表
     * 比如：select * from t_table_name where column1=? and column2=?, parameter1 , parameter2
     * @param <E> the returned list element type
     * @param statement Unique identifier matching the statement to use.
     * @param parameter A parameter object to pass to the statement.
     * @return List of mapped object
     */
    <E> List<E> selectList(String statement, Object parameter);

    /**
     * Retrieve a list of mapped objects from the statement key and parameter,
     * within the specified row bounds.
     * 在指定的行界中 检索符合条件的元组列表
     * 比如：select * from t_table_name where column1=? and column2=? limit offset,limit
     *
     * @param <E> the returned list element type
     * @param statement Unique identifier matching the statement to use.
     * @param parameter A parameter object to pass to the statement.
     * @param rowBounds  Bounds to limit object retrieval
     * @return List of mapped object
     */
    <E> List<E> selectList(String statement, Object parameter, RowBounds rowBounds);

    /**
     * The selectMap is a special case in that it is designed to convert a list
     * of results into a Map based on one of the properties in the resulting
     * objects.
     * 它被设计为转换结果的列表到基于结果对象中一个属性的map中.
     * 获取多条记录，，， 存入Map
     * Eg. Return a of Map[Integer,Author] for selectMap("selectAuthors","id")
     * @param <K> the returned Map keys type
     * @param <V> the returned Map values type
     * @param statement Unique identifier matching the statement to use.
     * @param mapKey The property to use as key for each value in the list.
     * @return Map containing key pair data.
     */
    <K, V> Map<K, V> selectMap(String statement, String mapKey);

    /**
     * The selectMap is a special case in that it is designed to convert a list
     * of results into a Map based on one of the properties in the resulting
     * objects.
     *
     * 它被设计为转换结果的列表到基于结果对象中一个属性的map中.
     * 获取多条记录，，， 存入Map
     *
     * @param <K> the returned Map keys type
     * @param <V> the returned Map values type
     * @param statement Unique identifier matching the statement to use.
     * @param parameter A parameter object to pass to the statement.
     * @param mapKey The property to use as key for each value in the list.
     * @return Map containing key pair data.
     */
    <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey);

    /**
     * The selectMap is a special case in that it is designed to convert a list
     * of results into a Map based on one of the properties in the resulting
     * objects.
     *
     * 它被设计为转换结果的列表到基于结果对象中一个属性的map中.
     * 获取多条记录，，， 存入Map, 可以分页
     *
     * @param <K> the returned Map keys type
     * @param <V> the returned Map values type
     * @param statement Unique identifier matching the statement to use.
     * @param parameter A parameter object to pass to the statement.
     * @param mapKey The property to use as key for each value in the list.
     * @param rowBounds  Bounds to limit object retrieval
     * @return Map containing key pair data.
     */
    <K, V> Map<K, V> selectMap(String statement, Object parameter, String mapKey, RowBounds rowBounds);

    /**
     * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
     * 游标提供与列表相同的结果，不同之处在于它使用迭代器懒散地提取数据。
     * @param <T> the returned cursor element type.
     * @param statement Unique identifier matching the statement to use.
     * @return Cursor of mapped objects
     */
    <T> Cursor<T> selectCursor(String statement);

    /**
     * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
     * 游标提供与列表相同的结果，不同之处在于它使用迭代器懒散地提取数据。
     * @param <T> the returned cursor element type.
     * @param statement Unique identifier matching the statement to use.
     * @param parameter A parameter object to pass to the statement.
     * @return Cursor of mapped objects
     */
    <T> Cursor<T> selectCursor(String statement, Object parameter);

    /**
     * A Cursor offers the same results as a List, except it fetches data lazily using an Iterator.
     * @param <T> the returned cursor element type.
     * @param statement Unique identifier matching the statement to use.
     * @param parameter A parameter object to pass to the statement.
     * @param rowBounds  Bounds to limit object retrieval
     * @return Cursor of mapped objects
     */
    <T> Cursor<T> selectCursor(String statement, Object parameter, RowBounds rowBounds);

    /**
     * Retrieve a single row mapped from the statement key and parameter
     * 根据sql获取一个元组，并转交给ResultHandler处理
     *
     * using a {@code ResultHandler}.
     * @param statement Unique identifier matching the statement to use.
     * @param parameter A parameter object to pass to the statement.
     * @param handler ResultHandler that will handle each retrieved row
     */
    void select(String statement, Object parameter, ResultHandler handler);

    /**
     * 根据sql获取一个元组，并转交给ResultHandler处理
     *
     * Retrieve a single row mapped from the statement
     * using a {@code ResultHandler}.
     * @param statement Unique identifier matching the statement to use.
     * @param handler ResultHandler that will handle each retrieved row
     */

    void select(String statement, ResultHandler handler);

    /**
     * 根据sql获取一个元组，并转交给ResultHandler处理，可以分页。
     * Retrieve a single row mapped from the statement key and parameter
     * using a {@code ResultHandler} and {@code RowBounds}
     * @param statement Unique identifier matching the statement to use.
     * @param rowBounds RowBound instance to limit the query results
     * @param handler ResultHandler that will handle each retrieved row
     */
    void select(String statement, Object parameter, RowBounds rowBounds, ResultHandler handler);

    /**
     * 插入，执行insert语句。insert into t_table_name value('1','2',3);
     * Execute an insert statement.
     * @param statement Unique identifier matching the statement to execute.
     * @return int The number of rows affected by the insert.
     */
    int insert(String statement);

    /**
     *  用给定参数对象执行INSERT语句， 任何生成的
     *  autoincrement值或selectKey条目将修改给定的参数
     *  对象属性。返回受影响的行数。
     * Execute an insert statement with the given parameter object. Any generated
     * autoincrement values or selectKey entries will modify the given parameter
     * object properties. Only the number of rows affected will be returned.
     * @param statement Unique identifier matching the statement to execute.
     * @param parameter A parameter object to pass to the statement.
     * @return int The number of rows affected by the insert.
     */
    int insert(String statement, Object parameter);

    /**
     * 执行UPDATE语句。返回受影响的行数。
     * Execute an update statement. The number of rows affected will be returned.
     * @param statement Unique identifier matching the statement to execute.
     * @return int The number of rows affected by the update.
     */
    int update(String statement);

    /**
     * 根据给定的参数，执行UPDATE语句。返回受影响的行数。
     * Execute an update statement. The number of rows affected will be returned.
     * @param statement Unique identifier matching the statement to execute.
     * @param parameter A parameter object to pass to the statement.
     * @return int The number of rows affected by the update.
     */
    int update(String statement, Object parameter);

    /**
     * 执行DELETE语句。返回受影响的行数。
     * Execute a delete statement. The number of rows affected will be returned.
     * @param statement Unique identifier matching the statement to execute.
     * @return int The number of rows affected by the delete.
     */
    int delete(String statement);

    /**
     * 根据给定的参数执行DELETE语句。返回受影响的行数
     * Execute a delete statement. The number of rows affected will be returned.
     * @param statement Unique identifier matching the statement to execute.
     * @param parameter A parameter object to pass to the statement.
     * @return int The number of rows affected by the delete.
     */
    int delete(String statement, Object parameter);

    /**
     * 提交事务。
     * 刷新批量语句，并提交数据库的连接。
     * Flushes batch statements and commits database connection.
     * 如果没有没有update，delete，insert调用的时候，不会提交连接。
     * Note that database connection will not be committed if no updates/deletes/inserts were called.
     * 如果要强制提交，调用commit(true);
     * To force the commit call {@link SqlSession#commit(boolean)}
     */
    void commit();

    /**
     *  提交事务。
     * 刷新批量语句，并提交数据库的连接
     * Flushes batch statements and commits database connection.
     * @param force forces connection commit
     */
    void commit(boolean force);

    /**
     * 回滚事务。
     *放弃挂起的批处理语句并将数据库连接回滚。
     * Discards pending batch statements and rolls database connection back.
     *    请注意，如果没有更新/删除/插入被调用，数据库连接将不会回滚。
     * Note that database connection will not be rolled back if no updates/deletes/inserts were called.
     *    强制回滚调用{@link SqlSession＃rollback（boolean）}
     * To force the rollback call {@link SqlSession#rollback(boolean)}
     */
    void rollback();

    /**
     * 强制调用回滚
     * Discards pending batch statements and rolls database connection back.
     * Note that database connection will not be rolled back if no updates/deletes/inserts were called.
     * @param force forces connection rollback
     */
    void rollback(boolean force);

    /**
     * 刷新批处理语句。
     * Flushes batch statements.
     * @return BatchResult list of updated records
     * @since 3.0.6
     */
    List<BatchResult> flushStatements();

    /**
     * Closes the session
     */
    @Override
    void close();

    /**
     * 清空本地会话缓存
     * Clears local session cache
     */
    void clearCache();

    /**
     * 检索当前的配置
     * Retrieves current configuration
     * @return Configuration
     */
    Configuration getConfiguration();


    /**
     *  检索一个Mapper(映射器)
     * Retrieves a mapper.
     * @param <T> the mapper type
     * @param type Mapper interface class
     * @return a mapper bound to this SqlSession
     */
    <T> T getMapper(Class<T> type);

    /**
     * 检索内部数据库连接
     * Retrieves inner database connection
     * @return Connection
     */
    Connection getConnection();


}
